
Examples of cassio usage
------------------------

Note: As of cassio 0.2.2, all short options (-b, -k, etc) have a
corresponding long option (--baud, --ff-block). The short options are
easier to type, but the long options are easier to remember. They may
be used interchangeably. See "cassio -h" or "man cassio" for details.


Loading tapes on a real Atari
-----------------------------

1. To load a .cas image with standard timing and baud rate, on the default
serial port (usually /dev/ttyS0):

   cassio file.cas

The easiest way to sync up the Atari and cassio is:

- Type the cassio command line, but do not press Enter to run the
command yet.

- Boot the Atari, get it ready to boot or CLOAD a tape, press Return
after the tone to start the loading process.

- Immediately after pressing Return on the Atari, press Enter on the
cassio command line, to start cassio running. Actually, it's OK to press
Enter and Return (on the Linux and Atari keyboards) simultaneously.

If you're a very fast typist, you can type the cassio command after
pressing Enter on the Atari. Basically, the Atari needs a minimum of 9
seconds of silence before the data from the first record (represented
by a long PRWT delay in the first data record), but it'll time out after
30-40 seconds of silence.

If you're late starting cassio, you can press Enter during the leader
(PRWT of the first data block) to immediately start sending the first
data block. If you're early starting cassio, you can pause it (space bar)
or rewind (comma).

If cassio and the SIO2PC had support for the motor control line, you
wouldn't have to manually sync them. Look for this in a future version
of cassio...


2. To use a different serial port:

   # full device name:
   cassio file.cas /dev/ttyS1

   # Same as above, with less typing:
   cassio file.cas 1

3. To load at 1.5x normal speed (not compatible with all images):

   cassio -f file.cas
   # or: cassio --fast file.cas


To load at 1.3x normal speed (more compatible than 1.5x):

   cassio -m file.cas
   # or: cassio --medium file.cas

If the Atari gives an error message or locks up with either -f or -m,
you can attempt a lower baud rate. The -f mode uses 880 baud, and -m
uses 850 baud. You can try:

   cassio -b750 file.cas
   # or: cassio --baud 750 file.cas

...to set the baud rate to 750 baud.

(note: In the current version of cassio, baud rates other than 600 are
ONLY supported on Linux, FreeBSD, NetBSD, and OpenBSD. You can still
use -f to get about a 10% speedup, even at 600 baud)


4. For a tape with more than one program/file, you can pick which file to
load. To load file #2:

   cassio -k2 file.cas
   # or: cassio --ff-stage 2 file.cas

(note: -k1 loads the first file, which is already the default action)

(note: the image information printed with "cassio -i" will tell you
how many files (aka "stages") are in the image)


5. You can load an image file from standard input:

   # (assuming "maketape" produces a valid .cas image on its standard
   # output:
   maketape | cassio

   # Same thing, using 2nd serial port:
   maketape | cassio - 1

   # works with pipes, too:
   # yes, this lets an Atari 8-bit stream media from the Internet!
   # Your 'net connection must be faster than 600 baud :)
   wget -O- http://somesite.com/tapes/file.cas | cassio


(note: If you want to turn off the image info and progress messages,
you can add -q (quiet mode) to any of the above)


Analyzing .cas images
---------------------

6. For a quick summary of the contents of a .cas file, you can run:

   cassio -i file.cas
   # or: cassio --info file.cas

This will print the same "Image Information as a regular load operation,
but not attempt to load the tape. Output looks something like:

cassio version 0.0.4 - Public Domain software by B. Watson, 2007

Reading cassette image from "q.cas"

Image information:
- Blocks:       214
- Data blocks:  212
- Data bytes:   27984
- Stages/Files: 2
- Estimated load time:     9:07
- IRG Type (stage/file 1): Short
- First data block: 3
- Image type: Boot tape (boot with START) or data file(s)
- Assuming this is a boot image. First stage boot info:
-   # of blocks:  4
-   Load Address: $6F93
-   Init Address: $1F3F

If there are bad/nonstandard blocks (including failed checksums), -i mode
will let you know. Some commercial or cracked games use a custom loader
with non-standard tape blocks, so cassio's warnings may not always mean
the image is bad.


7. For a detailed analysis of an image, you can run:

   cassio -I file.cas
   # or: cassio --details file.cas

This simulates the full loading process at high speed, but does not
actually send the tape data anywhere. In addition to the information
from the -i option, the length and PRWT of each block are printed,
along with a warning for each bad block.


8. If you need to see a dump of the actual data in the image, use the
-x (--hexdump) option:

   cassio -x file.cas
   # or: cassio --hexdump file.cas

This will give you a hex and ASCII dump of each tape block. Output looks
something like this:

Block 223: data, length   132, PRWT   265ms      92.5%,  15:52 left     
00:  55 55 FC 40 - 40 01 31 32 - 33 2C 32 30 - 30 2C 36 31  |UU.@@.123,200,61|
10:  2C 31 30 30 - 2C 38 31 2C - 32 30 30 2C - 37 32 2C 31  |,100,81,200,72,1|
20:  30 30 2C 36 - 38 2C 31 30 - 30 2C 37 32 - 2C 31 30 30  |00,68,100,72,100|
30:  2C 31 32 33 - 2C 32 30 30 - 2C 31 32 33 - 2C 32 30 30  |,123,200,123,200|
40:  9B 58 58 18 - 18 01 37 32 - 2C 35 30 2C - 36 34 2C 35  |.XX...72,50,64,5|
50:  30 2C 36 30 - 2C 32 30 31 - 9B 78 69 25 - 25 00 4D 41  |0,60,201.xi%%.MA|
60:  43 48 49 4E - 45 20 4C 41 - 4E 47 5D 20 - 54 4F 20 44  |CHINE LANG] TO D|
70:  52 4F 50 20 - 43 48 41 52 - 41 43 54 45 - 52 9B 82 69  |ROP CHARACTER..i|
80:  0C 0C 36 18                                            |..6.|

As you can see, there are readable ASCII (actually ATASCII) messages
visible in the ASCII dump on the right.

The hex dump is 16 bytes per line, with a - between each group of 4 bytes.
The data dumped is exactly what the Atari will see when loading the
image, including the baud-calibration bytes (the first 2 bytes, should
always be 55 55), the control byte (3rd byte, FC above), and the checksum
(last byte, 18 above). The actual data bytes in the record begin at the
4th byte and extend to the second-to-last byte.

Non-standard tape blocks may not have the checksum, control byte, or
baud-correction bytes, and may not even be 132 bytes in length. Some
images (especially commercial games) are designed to have non-standard
blocks, but if you're using wav2cas, lots of non-standard blocks is
often a sign that your .wav file is bad.

You can also use -x with the -i option, which will show hex dumps only of
bad/non-standard blocks.

Hex dumps produce a lot of output. cassio writes its human-readable
output to standard error (not standard output, since that may well be
the destination of an option such as -o or -X), so if you want to save
it to a file or pipe it through a pager such as "more" or "less", use
commands like:

   cassio -x image.cas 2>hexdump.txt

   cassio -x image.cas 2>&1 | less

(examples shown are for POSIX sh-style shells such as Bourne, bash, zsh,
or Korn shell.  I'm not sure if the 2>&1 syntax works in csh or tcsh,
I've never used them).


Simulating motor control
------------------------

9. During the loading process, if the Atari stops loading and starts
displaying a menu or intro, it's possible that the Atari wants to pause
the tape motor while this is happening. If you experience load errors
after such a menu/intro, you can try pausing the tape during the load

Normally, the first block after the menu will have a long (10-20 second)
PRWT gap. During the PRWT delay, just hit the space bar to pause the tape.
Eventually, the Atari should make its "press play" beep tone, at while
point you can press Space to have cassio start playing the tape image
again. If cassio gets ahead of the Atari (starts writing data before
the Atari is ready for it), you can recover by rewinding cassio (comma
or R key).

If you know you're loading a tape that needs to be paused during the
loading process, you can also use cassio's -a (--auto-pause) option.
This will cause cassio to automatically pause the playback on every
long (10+ second) gap. When the Atari is ready to load the tape again,
you can unpause playback (space bar) to continue. You can't use -a mode
unattended: cassio will wait until either the space bar is pressed or
the sun falls from the sky...


10. If you want to automate this process somewhat, you can pass the -p
(--patch) option:

   cassio -p8 image.cas
   # or: cassio --patch 8 image.cas

This will add a 15-second delay before sending the data of block #8. Note
that the block numbers start at 1, and include the FUJI and baud records
(on a normal image, block 3 is actually the first data block).

You can use multiple -p options, or specify many blocks in the same -p
option. You can also set the PRWT explicitly:

   cassio -p8=12000,50=30000,80,120=12000
   # or: cassio --patch 8=12000,50=30000,80,120=12000

...gives you a 12 second (12000 millisecond) delay in block 8, a 30 second
delay in block 50, a 15 second (default) delay in block 80, and another
12 second delay in block 120. The delay for a block happens *before*
the data from the block is loaded (it replaces the existing PRWT for
that block).

If using -p makes the tape load without manual pausing, you can use it
with the -E option to produce a new .cas image with the pause permanently
embedded (see "Fixing .cas images" below).

(note: a standard SIO2PC cable lacks the motor control line, so there's
no way to make cassio able to detect that the Atari wants to stop the
tape. Even the ATART doesn't support the motor control line when used
in SIO2PC mode. In the future, the Atarimax USB version of the SIO2PC
should solve this problem)


Real cassettes and/or a real cassette deck/drive
------------------------------------------------

(note: This section is mostly about cas2wav and wav2cas, which
were developed by ERS, not me (I just ported them to Linux). See
README_wav2cas.txt and README_cas2wav.txt for the actual documentation
for these utilities)

11. You have an Atari tape, but no Atari tape drive, and you want to
load the tape on your Atari (or on an emulator):

First, you'll need a tape player of some kind (a regular audio one,
not an Atari tape drive). Connect its audio output to your sound card's
line input, and verify that you can play an audio tape and hear it on
your PC speakers, and that you can record a .wav file (I purposely don't
recommend a recording utility, because I haven't found one that works
well for Atari tapes yet).

Set your recording app to 44100Hz (aka "CD quality"), 8-bit, mono.

Insert the tape in the tape player, press Play, and listen to your
speakers. The data sounds like a modem (really ear-piercing screeching
noises). The audio data will be coming out of one side only (should be
the right channel, but it's easy to accidentally hook the channels up
backwards). Some tapes also have an audio track on the left channel,
which plays through the Atari's TV speaker when the tape is loading;
wav2cas can't do anything with the audio track, so you should only record
the right (data) channel.

You want to adjust your recording levels so that channel is being recorded
loud and clear, but not loud enough to cause distortion. The other channel
(silence, or possibly audio) should be muted. If in doubt, it's better
to record too quietly than too loud.

Rewind the tape, press Play, and record the whole thing, all the squealing
and beeping. When you hear silence for a few seconds, keep listening:
there may be more data on the tape after a short period of silence.

When you're done, run:

   wav2cas audio.wav

If the recording is OK, you shouldn't see any errors. Usually it won't work
on your first try...

Eventually, you'll end up with a file called "audio.cas". Check this file
with "cassio -I" to make sure it doesn't have any really short tape blocks
(vast majority of tapes consist of only 132-byte records, and at least
the very first few records *must* be 132 bytes), or missing checksums,
or invalid baud correction bytes. If most of the blocks are longer than
132 bytes, but they're all the same length, the tape probably uses a
custom boot loader and non-standard tape format (257 bytes per record
is fairly common for there).

If it looks OK, you can try it with your Atari and cassio (see example #1,
above), or in your emulator of choice. If it won't work, see the
Troubleshooting section in README.txt.


12. You have an Atari computer, an Atari tape drive, and a .cas image.
You want to load the .cas image on the real tape deck (either because
you don't have an SIO2PC, or because you for whatever reason want a
real tape):

You'll need a regular audio tape recorder. Connect your sound card's line
output (or headphone jack, if there is no line out) to the tape deck's
line input. Actually, you should only hook up the right channel, and
leave the left channel tape deck input unplugged. If there is a balance
control or separate left/right recording levels on your tape deck, turn
the balance all the way to the right, or turn the left channel all the
way down. The sound card's line-out or headphone volume control should
be about 1/2 to 2/3 of the way up.

To create the .wav file, run:

   cas2wav file.cas

The result will be called file.wav, and will be fairly large. cas2wav is
a lot more reliable than wav2cas, so it should work fine...

Now, press Record/Play on the tape deck, and play the .wav file (choice
of player is unimportant; you may be able to just type "play file.wav",
or use XMMS, or whatever you usually use to play audio files).

If your deck has adjustable recording levels, you should adjust them
so the left channel signal occasionally just *barely* gets into the
red. If there are separate left/right controls, turn the left channel
all the way down. If you're using a deck with automatic gain control,
cross your fingers :)

When the .wav is done playing, stop the tape.

Now rewind the tape, pop it in your Atari tape drive, and enjoy. If it
won't load, check and see whether the .cas image will load with cassio.
If not, it might be a bad image. If it does work with cassio, maybe you
recorded on the wrong audio channel (data goes on the right channel),
or used a worn-out tape, or set the record level too high/low.

If you want, you can attempt to make a "fast mode" tape with cassio's
image editing mode (see next section). I have no idea whether a tape
made from a .cas image with a higher-than-normal baud rate will work
correctly on a real cassette deck. In theory, it should work, but I
don't know whether the A/D convertor inside the tape drive can handle
a higher baud rate than it was designed for. I haven't seen a working
tape drive in years, so I can't test it myself. So if you try this,
please let me know how well it worked!


13. You have an Atari tape, and you want to make a copy of it.

Well, the obvious way to make a copy is with a dubbing tape deck. This
works pretty well for copying first-generation tapes, but not so well
if the "original" is already a copy made this way. Also, the copies you
make this way are more susceptible to minor flaws on the tape media,
or dirty/misaligned heads on the tape drive.

What you need is a true digital copy of the data on the tape, recorded
freshly onto a new tape.

To do this, basically you follow the previous 2 examples (#11 and #12):
rip the original tape to a .cas image with wav2cas, then turn it back
into a .wav with cas2wav, then record it onto a new tape. Depending on
the age/quality of the original tape and the quality of your equipment,
the new tape may actually be a better copy than even a commercially-made
original tape. Assuming the old tape wasn't too damaged to read the
data from, the new tape should be a perfect copy with no signal loss,
unlike the copy you'd get with a dubbing deck.


14. You want to type in a program on your Atari and SAVE or CSAVE it,
but you don't have a real Atari tape drive (and for some reason you
can't or don't want to use a disk image).

In theory, it's possible to follow example #11, but with your Atari's
audio output being connected to your soundcard line in (right channel),
instead of a tape deck.

The audio output is on the 5-pin DIN connector on the 800 / 800XL /
1200XL / 130XE, or on an RCA jack on the XEGS, or the audio-out SIO bus
pin on any Atari model.

Unfortunately, the audio recorded from the Atari's DIN or RCA line-out
connector will have one major difference from the SIO connector's
audio-out line: It will contain both the cassette audio, and a constant
tone being played from one of the other POKEY channels. I'm not sure what
this tone is for, or why it's not present on the SIO pin, but it's very
noticeable.

If you're recording straight from the SIO pin, your .wav file is probably
not too bad (possibly the volume is too high/low, see below).

If you record from the DIN/RCA jack, you'll have to process the .wav file
to filter out the extra POKEY channel tone. I've found that this command
works pretty well (may also be helpful for SIO pin audio, too):

   sox audio.wav audio2.wav filter 3800-6200 15000 16

This command takes a while to run, even on a fast multi-GHz machine.
If you don't have sox installed, it should be available for your Linux
distribution as a standard package (e.g. Debian "apt-get install sox"),
or you can use some other audio tool like Audacity, provided it has a
bandpass filter option (the 3800 is the low cutoff of the band, and the
6200 is the high cutoff. With tools other than sox, these numbers might
have to be tweaked a bit).

The filtered "audio2.wav" created by sox should be usable, though we
still might need to address the volume issue...

If wav2cas reports 595 baud for some records, and 604 for others, and/or
you find a lot of 127- or 128-byte records in "cassio -I" output, you
probably need to increase the volume some. The correct way to do this,
of course, is to adjust the levels and re-record the .wav file. However,
this can get time-consuming. Instead, try:

  sox file.wav file2.wav vol 3

The "3" is a floating point number; values less than 1 decrease the volume
and values greater than one make it louder. If sox complains about clipping,
try a lower number. The volume-adjusted output is in "file2.wav".

(note: you could also combine the filter and vol effects, if you already
knew you needed to:

  sox audio.wav audio2.wav filter 3800-6200 15000 16 vol 3

...see "man sox" for more information)


Now, try wav2cas again, then run the resulting .cas through "cassio -I".

If you end up with a file that contains 133-byte blocks, but otherwise
looks OK (all blocks are 132-133 bytes), this is due to a quirk in
wav2cas... actually, it's because digital audio can only be dealt with in
whole numbers of samples, but one bit at 600 baud (sampled at 44.1KHz)
would actually be 73.5 samples. wav2cas has to guess whether 73 or 74
samples represent one bit, and sometimes it guesses wrong... There's
not much to be done about this except to increase the sampling rate
(currently wav2cas won't support anything higher, but a future version
might support 48KHz. One 600-baud bit sampled at 48000 samples/sec is
exactly 80 samples, which should improve reliability).

Anyway, to fix the 133-byte problem, you can use the -L flag with cassio.
To play back an image like this:

  cassio -L image.cas
  # or: cassio --fix image.cas

To permanently fix a file like this, use a command like:

  cassio -E output.cas -L input.cas
  # or: cassio --edit output.cas --fix input.cas

Note that, if cassio still reports nonstandard/invalid blocks, the file
had other problems that the -L can't fix. Sometimes, you just have to
go back and re-record the .wav file...

Of course, if you've got an SIO2PC and AtariSIO/sio2linux, you're a lot
better off booting a disk image and saving your program to that! It's
quicker, easier, and known to work. Sometimes, though, you'll code up a
beautiful demo in BASIC, only to find out that you forgot to boot DOS,
so you *can't* save it on disk! The cassette can save you in a case like
this; it is slow, but at least its driver is always present.. If this
happens, and if you own a real Atari tape drive, you don't need cassio
at all for this, just a blank tape...


Fixing (editing) .cas images
----------------------------

15. You want to change the description stored in a .cas file

  cassio -E output.cas -D 'My new description' input.cas
  # or: cassio --edit output.cas --description 'My new description' input.cas

The -E option puts cassio in image editing mode. It takes a filename,
which MUST be different from the input filename. This is a safety feature,
to keep you from accidentally wiping out your original .cas images.

After the above command finishes, there will be a new .cas image called
output.cas, which is exactly the same as input.cas, except that its
description (in the FUJI record) has been changed. You should test the
new image, and if you're happy with it, you can delete the original
input.cas and rename output.cas to input.cas.

In -E mode, nothing is written to the serial port. In fact, you can use
-E to edit an image without having a serial port at all.

You can't directly make your changes to the original file. This command
will fail:

  # BAD command, will FAIL:
  cassio -E input.cas -D'New Description' input.cas

...but you can do it like this:

  # good command, works
  cassio -E- -D'New Description' input.cas

  The original input.cas file will still exist, renamed to input.cas~
  (with a tilde on the end), and the output of -E will be written to a
  new file named input.cas.

You *can* use cassio edit mode as a filter, like a standard UNIX utility.
This works:

  # Read .cas image from standard input, write to standard output:
  cassio -E- -D'New Description' -

Any time cassio exits with an error (!!!Fatal message), its exit status
will be non-zero (indicating failure). If cassio exits normally, its
exit status will be 0 (indicating succedd), so you can use it in a shell
script like so:

  # -q (or --quiet) is cassio's "quiet mode"; still shows warnings. Use -Q
  # (or --silent) to suppress almost all warnings, or 2>/dev/null to
  # suppress standard error output entirely.

  if cassio -q $FILE; then
    echo "$FILE is a valid cassette image"
  else
    echo "$FILE is bad"
  fi


16. You want to change the timing of a .cas image permanently, either to
fix a bad image, or to avoid having to pause cassio manually during loading

Use the -p option (described in example #10, above) with the -E option.
This will create a new .cas image whose timing reflects the adjustments
made by any -p, -t, baud rate, or -l -M -s options.

Suppose you needed block #8 to have a 15-second delay:

  cassio -p8 -E output.cas input.cas

-E mode can use any of the options marked with [*] in the help ("cassio
-h") to alter the output image. The -z (normalize timing) option is
particularly useful.

Another option you might find useful is -t. It allows you to adjust
the timing over the entire image, either adding/subtracting a constant
amount of time to each record, or multiplying the PRWT of all records by
a constant. You might use this with an image that was made with wav2cas
from a misadjusted tape deck that plays too fast/slow (though you'd be
better off using a .wav editor to speed up/slow down the .wav instead,
or even better, fix/replace the tape deck).

Another option that you might use is -z (--normalize).

17. You want to create a "fast loading" tape that will work on an actual
Atari tape drive

(note: not tested on a real tape drive yet! In theory, this should work
with baud rates up to about 880, as far as the Atari is concerned,
but it remains to be seen whether the A/D convertor inside the tape
drive can handle that speed. Modest speed increases (660, 700 baud)
should be OK for sure).

  cassio -f -E output.cas input.cas
  cas2wav output.cas
  (then record output.wav on a real tape)

The -f option tightens up the timing and sets the baud rate to 880. This
may not work on a real tape. You can try -m mode instead (leaves the timing
alone, sets baud to 850), or just pick a baud rate with the -b option:

  cassio -b660 -E output.cas input.cas

Also, you can shorten the long 20-30 second gaps between boot tape stages
with the -l option, which can be used by itself or with any of the other
options (the -f option implies "-l12000"). Remember that the Atari OS
needs to see at least a 9-second gap between two "files" on the tape,
so don't use anything less than -l9000 (and -l10000 is a lot safer).

18. You've just created a .cas image with wav2cas, and it looks mostly
OK except that some of the blocks are 133 bytes (where they should be
regular 132-byte blocks).

Use the -L option, which is specifically intended for this use. It removes
the last byte from 133-byte records (wav2cas sometimes detects an extra
"phantom" data byte, due to the way audio sampling works).

Normally, the extra 133rd byte won't actually cause problems even if
you leave it there (the Atari will just ignore it), but it will cause
cassio to skip the checksum checking for that block (hiding what might
be a real problem with the .cas image).

  cassio -L -E output.cas input.cas

  # same thing, "in place" (new file will be "input.cas", old one
  # renamed to "input.cas~"):
  cassio -L -E- input.cas

(note: the -L option will also work without -E, or with -i/-I, so you can
"preview" what the results will be)


19. You want to change the actual data in the .cas image (e.g. to patch
the Atari program or data file)

cassio doesn't support this directly. Instead, you can extract
the data with the -o, -eo, or -X options, edit the resulting
file (with a hex editor, or a text editor for text-like data, or
disassemble/patch/reassamble for machine language code).

Use something like:

  # for binary data or ML code:
  cassio -o code.bin image.cas
  (edit code.bin as desired)
  cassio -c newimage.cas code.bin

or:

  # for multi-stage boot tapes:

  cassio -X game image.cas
  # or: cassio --split-files game image.cas
  # each load stage will be in a separate file: game.01 game.02 game.03 etc.

  (edit stage file(s) as desired)

  # create a new .cas image for each stage
  for i in game.??; do
    cassio -c $i.cas $i
  done

  # Join the stage-images together to create the complete image.
  # See "Fixing .cas images" example #18, below, for -UE- explanation.
  cat game.??.cas | cassio -UE- > newimage.cas

...or:

  # for text files, including BASIC/assembler source made with LIST "C:",
  # add the -e option:
  cassio -eo code.txt image.cas
  (edit code.txt as desired)
  cassio -s4000 -ec newimage.cas code.txt
  # or: cassio --short-gap 4000 --eol --create newimage.cas code.txt

...or even:

  # Use standard UNIX tools to operate on LISTed Atari BASIC:
  # Correct a typo in the program, and delete line 100!
  cassio -eo - image.cas | sed 's/Viedo/Video/g'| \
    grep -v '^100 ' | cassio -s4000 -ec newimage.cas -

(note: the "-s4000" is required because ENTER-format tapes have 4-second
inter-record gaps, unlike boot tapes or CLOAD tapes).

The -o (--dump) option reads the data from the .cas image and puts
it in a file on your filesystem. The data does NOT include the
baud/control/checksum bytes for standard 132-byte Atari tape blocks
(though nonstandard-sized blocks are included verbatim, since there's
no way to tell which bytes, if any, are metadata). If your .cas file
contains "phantom bytes" put there by wav2cas, you can add -L to the
command line to strip them out (see above example).

The -c (--create) option creates a .cas image containing the data from a
file on your filesystem. The .cas will contain 132-byte tape blocks, with
the baud/control/checksum bytes set correctly so the Atari can read it.
With -c, you can write Atari code with a 6502 cross-assembler on your
workstation, then boot it on the Atari.

The -eo (--eol --dump) and -ec (--eol --create) options work the same
as -o and -c, but they also translate Atari EOLs ($9B) to and from UNIX
end-of-lines ($0A, aka "newline"). If you're working with DOS-style text
files that have CRLF line endings, use "dos2unix" or a similar utility
to turn them into regular UNIX-style text files first. With -ec, you
can actually write Atari BASIC code in vi or emacs, then ENTER it into
the Atari...

With -c and -ec, the first record created will have a a PRWT of 15 seconds
byt default, and all other records will have a PRWT of 250ms. You can
change the default timing with the -l, -s, -p, and/or -t options. To
create an ENTER-compatible tape, use -s4000 or so.

20. You have two .cas images, and you want to find out whether they
contain the same data.

Use cassio's -v option:

   cassio -v foo.cas bar.cas

Any differences in the data in the data blocks of the two files will be
reported, along with a count of differing blocks. Also, cassio's exit
status will be 0 (success) if there are no differences, or 1 (failure)
if there are any differences.

The PRWT timing and non-data blocks are not compared, but the
baud-correction, control, and checksum bytes ARE compared.

If you want to compare the data *without* the baud/ctrl/cksum bytes, use
"-o" or "-eo" to dump the data streams to files, then use the standard
UNIX diff or cmp utilities to compare them.

21. You have an Atari tape drive and an Atari tape, and you want to copy
the tape without using a .wav file.

Use cassio's -R option to attempt this:

   cassio -R tape.cas
   # or: cassio --read-sio tape.cas

These instructions assume you have an Atari computer with BASIC,
connected to the SIO bus. The Atari computer is only needed for turning
on motor control. If you know how (I don't!), you should be able to add
a motor control override switch to your tape drive, and do without the
Atari computer.

Insert tape in drive, press Play, then start the motor: On the Atari,
type POKE 54018,60, or just start loading the tape normally (boot with
START, CLOAD, etc).

Press Return on the POKE command at the same time as you press Enter
on the cassio command. The tape motor will start, and cassio will begin
capturing data from the tape drive as it's decoded.

Once you reach the end of the data on the tape, or if the tape has
multiple files and you want to stop after the first file, press any key
on the Linux box, which will stop the data capture and print information
on the newly-created .cas file. If cassio doesn't receive any data for
60 seconds, it will stop capturing on its own (the extra silence at the
end of the tape will not affect the resulting .cas file, so it's OK to
leave it unattended).

To turn off motor control on the Atari, POKE 54018,52 or just turn off
the Atari.

If all went well, you should have a good .cas image.

Unfortunately, all is not likely to go well... tapes and tape drives are
subject to all sorts of problems (incorrect motor speed, stretched tape)
that affect the baud rate. The Atari computer's OS was designed to work
around these issues by doing on-the-fly baud calculations, using the first
2 bytes of each cassette block to calibrate the baud rate for the rest of
the block.

PC-style serial ports don't contain any hardware or software to do the
auto-baud-adjustment, so the tape motor speed has to be exactly right
for this to work at all. Stretched tape causes the same problem: it
manifests itself as slowed-down playback. The internal A/D converter in
the tape drive just emits bits as they are detected, at the speed that
the tape moves over the head, which happens to be 600 baud for a good
tape and properly calibrated drive.

If you have problems, you can try adjusting cassio's baud rate with the
-b option, but this may not help if only part of the tape is stretched.
If you consistently have problems with multiple different tapes, you may
be able to adjust the motor speed of your tape drive and/or replace the
drive belt (see if you can find a field service manual for your unit, or
ask on AtariAge).

Note: ALL 410 units (even ones that have been sealed in a box for 25
years) suffer from bent/kinked belts, due to a design flaw.  The only
way to avoid belt damage on a 410 is to use it for at least a few seconds
every week or so.

Note: MOST 1010 units suffer from degraded belts, simply because the belts
are very thin, and they decompose back into crude oil as the years go by.

For particularly cantankerous tapes, try capturing 3 times with slightly
different baud rates, and/or on different tape drives, then using cas2cas
to (try to) build one good image out of the 3 bad ones.

Sometimes the tape is unevenly wound on the reels, which causes
similar problems as stretching, but it can usually be corrected by
fast-forwarding the tape all the way to the end, then rewinding all the
way to the beginning.

The -R option may be completely useless for some tapes/drives. In that
case, try wav2cas. It's a lot more tolerant of varying baud rate.


22. You have several programs and/or data files for the Atari, and you
want to combine them into one .cas image.

You *can* just use cat:

  cat program.cas data.cas > prog_and_data.cas

When you playback prog_and_data.cas, cassio will warn about extra baud
and FUJI blocks, but no harm is done by these warnings (the blocks are
just skipped). However, some other programs that use .cas files may be
confused by them, so it's not a good idea to distribute such .cas images
to the whole world...

The -U (--strip) option, in -E (--edit) mode, will remove these
blocks. You could fix prog_and_data.cas:

  cassio -U -E- prog_and_data.cas
  # or: cassio --strip --edit - prog_and_data.cas

...or you could have done it in one step:

  cat program.cas data.cas | cassio -UE- > prog_and_data.cas

Note that -U will remove all but the first FUJI block (which must be
block #1 for all valid .cas files), and will remove any baud blocks
that set the baud to the same as it already was (though it will leave
any baud blocks alone, if they actually *change* the baud rate).

For files with no baud block before the first data block (or even no baud
block at all), -E will always insert a baud block before the first data
block (normally block #2), whether or not -U is given.  If this happens,
the generated baud block will set the rate to whatever the -b option says,
or 600 (standard Atari rate) by default.

A file containing no baud block before the first data block is technically
not a .cas image (doesn't meet the .cas image spec), but cassio is polite
enough to handle them anyway. Other tools may not be so forgiving...


--
B. Watson
urchlay (at) urchlay (dot) com
Urchlay on www.atariage.com
